InfoMagic Internet Tools 1993 July/Internet Tools.iso/RockRidge/mail/sendmail/uk-sendmail2.1/Docs/Guide.ms

Text File | 1991-06-11 | 24.8 KB | 854 lines

.TL
Sendmail Configuration Package UK-2.1
.sp
User Guide
.AU
Jim Crammond
.AI
Dept of Computing,
Imperial College, London, England
.AU
Jem Taylor
.AI
Dept of Computing Science,
University of Glasgow, Glasgow, Scotland
.DA 22 March 1989
.LP
.NH
The Configuration Description File
.NH 2
Purpose
.LP
The configuration description file names all the options and data required for
producing a particular sendmail configuration file.
It is invoked by the command
.IP
% Config <configfile>
.LP
We recommend that all configuration description files be named
.I config. <name>
where <name> is the same as the value of the config=<name> directive in the
configuration description.
.NH 2
Mandatory directives
.LP
The following directives are obligatory in the file
and must come before any domain or channel declarations:
.IP config=<name>
This specifies the
.I "configuration name"
which is usually the hostname of the target system, or the name of a
class of hosts such as "slave". It simply determines the names of certain
files created when making the configuration.
.IP domain=<domainname>
This should be the official domain name as registered with some administrative
body such as the NRS or NIC.
In the absence of any such official name, a pseudo-domain-name such as 'uucpname'.uucp
should be used; however this should be done only
as a strictly interim measure until a name is officially registered.
.NH 2
Optional directives
.LP
The following directives are optional, but must come before any domain
or channel declarations:
.IP configdir=<subdirectory>
This specifies the subdirectory in which to create the files that
make up the sendmail configuration file. By default, this is set
to the configuration name.
.IP tabledir=<subdirectory>
This specifies the subdirectory which contains the domain
and channel tables. This allows tables for several configurations
to be stored in the same directory, if desired.
By default, this is set to the configuration name,
.IP postmaster=<mailbox>
This is the local mailbox from which errors are generated.
Sensible values include "POSTMASTER" (the default) and "MAILER-DAEMON".
.IP options=<option1>,<option2>,...
This directive may be used to select optional processing. Options include:
.RS
.IP multihost
The configuration is for a "multihost" site - i.e. more than one host will
show itself to the outside world with the domain name <domainname>.
In addition, this host has a host specific domain name of the
form `hostname`.<domainname>
.IP nrsformat
This enables addresses with domains in the NRS domain order to be
recognised and generated. This option MUST be specified if the janet
channel is used.
.IP nameserver
For sendmails which contain nameserver code, this makes a
request to the nameserver to obtain the official domain name of
a host/domain. It should not be specified unless all sendmails
which will use the configuration have the nameserver code compiled in.
.RE
.IP install=<flags>
Set the flags to be used in the call to Install.sh from the Makefile created
by Config (see section 4).
.NH 2
Domain declarations
.LP
Domain declarations may be repeated as often as necessary and take the following form
.IP
domain
.I type
file="
.I filename
"
.LP
type may be 'std', 'ida' or 'top'.
A domain declaration of the standard type 'std' indicates that
.I filename
is a domain table to be compiled directly into sendmail rules and classes.
If the type is 'ida' then instead
.I filename
will be compiled into a dbm database file which is called from
the sendmail configuration file using a dbm lookup facility.
The type 'top' specifies that
.I filename
is a domain table listing top level domains.
.NH 2
Channel declarations
.LP
Channel declarations may also be repeated as often as is needed
for each channel. The existance
of a channel is declared by one or more declarations of the appropriate type.
The form of a channel declaration is
.IP
channel
.I type
file="
.I filename
" [,
.I channeloption ]*
.LP
where
.I type
is a channel type,
.I filename
is a channel table, and
.I channeloption
is an option specific to this channel.
.KS
.NH 3
Channel types
.LP
Valid channel types include:
.IP
local ether tcp uucp janet
news decnet csnet xerox top
.KE
.LP
Details about the channel tables are given in section 3.
.NH 3
Channel options
.LP
Channel specific options include the following possibilities:
.IP "local channel:"
.RS
.IP showldomain
Local addresses are presented locally with the local domain name appended.
By default, the local domain name is
stripped from addresses in headers leaving just the username.
.IP shownrs
All domain addresses are presented locally
in NRS domain ordering (i.e. big-endian).
By default, all addresses are presented in RFC822 order.
The "nrsformat" option is required with this option.
.IP showuucp
Addresses containing two or more hostnames are presented locally
in uucp bang style.
.RE
.IP "uucp channel:"
.RS
.IP sysname=<name>
Set the uucp system name this machine is known by to <name>.
.IP "muucp "
Use the muucp program to interface with uucp
(supplied in the Support directory) instead of calling uux directly.
.RE
.IP "janet channel:"
.RS
.IP hhsend
Set the mailer specification to use hhsend (York X.25) instead of
ni_send (Unix-Niftp).
.RE
.IP "news channel:"
.RS
.IP relayed
This indicates that
.I all
news is relayed to another host.
.RE
.IP "uucp, janet, decnet, csnet and xerox channels:"
.RS
.IP auth
Set the mailer specification to invoke the authorise program for
mail authorisation by host. The authorise program in the Support
directory needs to be installed to use this option.
.RE
.IP "all channels:"
.RS
.IP ida
Rather than generate sendmail rules directly from the channel table,
create an IDA database file and arrange for sendmail to lookup
this file instead (see section 3).
The configuration should not be exported to another host unless
that host also has access to the same file by the same name.
This option does not apply to local, uucp or news channels.
.IP "ldomain=<domainname>"
Messages sent on this channel will have the local domain name
stamped as <domainname> rather than the official domain name.
This has no effect on the local channel.
.RE
.NH
Domain Tables
.NH 2
General
.LP
It is recommended that you have some idea of what domains are before
you start. RFC819 (supplied with the sendmail documentation) is a good
starting point for this.
.LP
The domain tables provide the information that allows sendmail
to expand host/site names or abbreviated domain names to fully
qualified domain names.
.LP
The tables consist of rules (1 per line) which consist of two
strings separated by white space. Essentially, any address whose
domain part ends in the string given on the LHS of a rule will be
expanded to the string given on the RHS.
.LP
For example, if the following entry was in the domain tables
.DS I
hw hw.ac.uk
.DE
.LP
then a user can give the address
.I jim@hw
and sendmail will expand this to the fully qualified name
.I [e-mail].
Also, this will expand
.I [e-mail]
to
.I [e-mail] .
.SH
Notes
.IP (1)
The above line will NOT cause
.I [e-mail]
to be expanded to
.I [e-mail] .
To achieve this, the line
.DS I
ac ac.uk
.DE
.IP
must also be included in the domain tables.
(This is a change from previous versions of UK-sendmail).
.IP (2)
The names in the domain tables must be given in RFC822
(little-endian) form with the most general part rightmost. e.g. hw.ac.uk,
regardless of whether the "nrsformat" option has been specified.
.LP
Probably the minimum information you need to specify in the domain tables
is a mapping from your host name to your domain name, e.g.
.DS I
sun6 sun6.cs.hw.ac.uk
.DE
.LP
This would mean users would always have to give fully qualified addresses
to send mail elsewhere.
.LP
In the NRS registration scheme, domain names are structured with "uk"
at the top level, with two main subdomains distinguishing
academic from commercial sites,
and institution or company names at the third level.
.LP
A sensible choice for domain tables in such a scheme would be to
include siblings of the subdomains that make up your domain name
starting from the institution name (third level),
e.g. for the host
.I sun6.cs.hw.ac.uk
this means all subdomains of "ac.uk", "hw.ac.uk" and "cs.hw.ac.uk".
.LP
You can add further information, for example, you may wish to specify
all the subdomains of "co.uk" as well as "ac.uk". Beware of naming
conflicts, however, as there are some cases in the NRS that could
cause problems.
For example, if the entry
.DS I
kl kl.york.ac.uk
.DE
.LP
was in your tables, then mail to Keele Computer Science addressed as
.I [e-mail]
will be expanded to
.I [e-mail]
instead of
.I [e-mail]
(the full address
.I [e-mail]
will work correctly, of course).
The
.I Domcheck
program can spot cases where you have placed entries in your tables
with the same LHS but different RHSs.
.KS
.LP
Domain name aliases can also be included in these files; so
for example, you could convert NRS abbreviated form names to standard form
with the following entries:
.DS I
cs.gla.ac.uk cs.glasgow.ac.uk
clust.hw.ac.uk cluster.heriot-watt.ac.uk
doc.ic.ac.uk doc.imperial.ac.uk
.DE
.KE
.LP
so that
.I [e-mail]
will be aliased to
.I [e-mail] .
.LP
It should be noted that many domain aliases placed in a standard type
domain table can result in generating a large
sendmail configuration file, so if you map all (700+) abbreviated form NRS
names to their standard form then your sendmail may run rather slowly!
.LP
This is an example where IDA sendmail is useful; by changing the domain
table type to 'ida', a dbm(3) file is created from which IDA sendmail will
lookup the domain directly. The effect is exactly the same as before only
probably much faster, especially as sendmail does not have to load
such a large configuration file when it is invoked.
.LP
If you have Yellow Pages compiled into your /usr/lib/sendmail program,
and your yellow pages database only contains entries for hosts within
one domain then you can use a rule such as:
.DS I
$%y $2.cs.hw.ac.uk
.DE
.LP
to map all of these hostnames to domain names.
.LP
Finally, a "#" in the tables starts a line of comment. All text after
the "#" up to the next newline is ignored.
.NH 2
Top Level Domains
.LP
Top-domain tables are treated specially.
These files contain a list of top level domain names.
.LP
The format of these tables is compatible with the top channel
tables: a top level domain name on the LHS and a relaying domain on
the RHS, e.g.
.DS I
uk ukc.ac.uk
.DE
.LP
Thus you can link the top channel and top domain files, if you wish.
Alternatively,
if the top channel file contains a special directive such as
"ALL" or "DEFAULT", then a single column list of top level domains
can be used for the domain table.
.NH 2
Shorthand Notation
.LP
Where a domain table entry is a domain specification rather than an alias,
i.e. the LHS is a single token which appears as the first subdomain on
the RHS, then the LHS can be omitted. For example,
.DS I
cs cs.glasgow.ac.uk
.DE
.LP
can be entered as
.DS I
cs.glasgow.ac.uk
.DE
.LP
but
.DS I
mcvax cwi.nl
.DE
.LP
must be given as shown. This shorthand notation makes it possible to use
the same file for both local network domain data and local ethernet channel
data (see later).
.NH 2
Examples
.LP
The directory Examples contains sample domain tables.
These can be used as a starting point for creating your domain tables.
.KS
.NH
Channel tables
.NH 2
General
.LP
Having expanded addresses into fully qualified domain addresses, sendmail
then selects the appropriate mailer and routing. The channel tables
provide the information to associate a domain name with a mailer (or channel)
and transport address (or route).
.LP
The channel tables contain rules (1 per line) containing
two strings separated by white space. In general, the string on the LHS
is a fully qualified domain name and the string on the RHS is the route
or "host to send to", e.g.
.IP
cs.hw.ac.uk sun6
.LP
specifies that addresses of the form
.I [e-mail]
should be send to the host
.I sun6 .
.KE
.LP
If sendmail fails to find a match for a domain, e.g.
.I "sun4.cs.hw.ac.uk"
in the main channel tables, then it retries with successively higher level
domains, e.g.
.I "cs.hw.ac.uk",
.I "hw.ac.uk"
and
.I "ac.uk" .
If these fail then the top level domain relaying rule for
.I "uk"
is applied and  matching begins again with the domain given as the relay for
.I "uk".
.LP
The actual format of the channel tables depends on the mailer. The minimum
information you need to specify depends on what mailers you
have, but is essentially:
.IP (a)
the domain name(s) the local host is known by,
.IP (b)
the names of directly connected hosts,
.IP (c)
the list of top level domain relaying sites (see below).
.LP
The maximum information you can specify is limited by practical
considerations such as the number of rules sendmail can cope with
before running very slowly. As a guide, if more than 100 rules are
generated in the channel section of the configuration, you may wish to cut down
the number of entries in the channel tables.
.LP
Careful use of top level domain relays and/or wildcards will often help.
For example, if
.I ukc.ac.uk
is specified as the uucp relay,
then there is no need to specify any routes for uucp sites which has
"ukc!" in the path (ukc.ac.uk has an extensive nameserver to do
further routing).
.LP
Those with IDA sendmail can compile some large channel tables into
ida databases. This is particularly useful for the janet channel.
Note that ida channel tables may not contain wildcards.
.NH 2
Channel Table Formats
.LP
The actual format of the channel tables depends on
the channel type (i.e. mailer) that is specified in the configuration
description file. These are listed below. Note, however, that
all of the channel tables use the same convention for
comments as used for the domain tables.
.NH 3
local channel
.LP
This contains a one-per-line list of (fully qualified) domain names
which are to be treated as local mail. In a 'multihost' this must
include the site domain name and the host specific domain name, e.g.
.DS I
cs.hw.ac.uk
sun6.cs.hw.ac.uk
.DE
.LP
In order to allow hosts to share the same sendmail configuration file,
the keyword "LHOST" must be used in place of the actual hostname, i.e.
.DS I
LHOST.cs.hw.ac.uk
.DE
.LP
LHOST is substituted by the hostname (as returned by
.I hostname(1)
) when
sendmail starts up. Obselete names still in use, such as
.IP
hwcs.uucp
.LP
should also be included here.
.TA
.NH 3
general case channel
.LP
The ether, tcp, xerox, decnet and csnet channels all use the same
"standard" channel format, as described above; a domain name on the LHS in
little-endian order, and a hostname to send/relay to on the RHS.
If the host name on the RHS is the same as the first subdomain, then the
RHS can be omitted. Thus
.DS I
sun3.doc.ic.ac.uk
.DE
.LP
is equivalent to
.DS I
sun3.doc.ic.ac.uk sun3
.DE
.LP
This shorthand notation makes it possible to use the same file both as an
ethernet channel table and local domain table, for example.
.KS
.LP
In addition, the LHS can contain
.I wildcards ,
specified by "%s", meaning "one or more tokens". So,
.DS I
%s.ncr.com sun4
.DE
.LP
sends anything ending
.I .ncr.com
to the uucp relay host,
.I sun4 .
The RHS can also contain wildcards which correspond to the tokens matched
by the wildcard on the LHS. For example, an ether channel with
.DS I
%s.ee.ic.ac.uk ee.%s
.DE
.LP
would send mail for
.I [e-mail]
to the host
.I ee.vax2
(as given in /etc/hosts).
.KE
.KS
.LP
If sendmail supports Yellow Pages, and the Yellow Pages
.I hosts
database only contains entries for hosts in one domain, then the
special token "$%y" may be used in the following way to specify that mail
to all hosts in the yellow pages database be sent directly:
.DS I
$%y.cs.glasgow.ac.uk $2
.DE
.KE
.SH
Notes
.IP (1)
The Yellow Pages special token may not be used in entries containing wildcards.
.IP (2)
Wildcard entries are processed after non-wildcard entries. So, given
the following entries in a tcp table:
.DS I
%s.cs.ucl.ac.uk %s.cs.ucl.ac.uk
cs.ucl.ac.uk cs.ucl.ac.uk
.DE
An address such as
.I [e-mail]
will be routed to
.I cs.ucl.ac.uk
by the second rule, and not sent direct. However, wildcard rules are processed
in the order in which they are presented, so
.DS I
%s.hw.ac.uk hw-relay
%s.ac.uk ac-relay
.DE
should be used, rather than the reverse order.
.IP (3)
Internet based sites usually pass addresses to the tcp channel
by default; this can be achieved with entries in the tcp
channel table like:
.DS
# all arpa addresses to tcp
%s.edu %s.edu
%s.com %s.com
.DE
for each of the arpa-based top level domains.
.NH 3
janet channel
.LP
The LHS domain name is in
.I big-endian
form in this table. The RHS is a "hostname" to send to which corresponds
to the entry given in the ftp host tables. For example,
.DS I
# hw.cs is directly on janet
uk.ac.hw.cs uk.ac.hw.cs

# hw.ee uses hw.cs as an application relay
uk.ac.hw.ee uk.ac.hw.cs
.DE
.LP
The LHS and RHS may contain wildcards in the same way as in the
general case channel, thus:
.DS I
uk.co.stc.%s uk.ac.ukc
.DE
.SH
Notes
.IP (1)
If the RHS is the same as the LHS, it can be omitted; if it differs
then correct JNT Application Relaying is done.
.IP (2)
In previous versions of UK-sendmail the janet channel would automatically
assume that all "uk.ac.<name>" domains are to be routed to "uk.ac.<name>"
and all "uk.co.<name>" domains are to be routed to "uk.co.<name>".
It is now necessary to use the lines
.DS I
uk.ac.%s
uk.co.%s
.DE
to achieve this effect if desired.
.IP (3)
If you do not map standard form NRS names to abbreviated from (or vice versa)
in the domain tables then any entries in the janet channel table should
include both forms of name on the LHS.
.IP (4)
In previous versions of UK-Sendmail, incoming mail from the Greybook mail
listener was passed to sendmail with a command line like
.DS C
/usr/lib/sendmail -oiY -oMsuk.ac.sender.name ...etc...
.DE
This version requires that the sender domain be set in macro
.I S
rather than
.I s
for correct Via: headers to be generated. Use
.DS C
/usr/lib/sendmail -oiY -oMSuk.ac.sender.name ...etc...
.DE
to achieve this, by means of the MAILFMT directive in
.I /etc/niftptailor
if using the Unix-Niftp package.
.IP (5)
When generating janet channel tables from data derived from the NRS by the
.I c-nrs
program, beware that it is assumed that the right hand side points to a
site that the delivery agent will know about. If the right hand side is
itself an application relay, then sendmail will not recursively resolve it.
When using the Unix-Niftp package this is not normally a problem, unless
one of the hosts involved is particularly demanding about JNT mail
application relaying; Unix-Niftp will find the DTE address of the final
application relay, but does not modify the JNT mail header when doing so.
.IP
The authors believe that any such problems should be dealt with during
the generation of the text of the channel table, rather than by sendmail.
.LP
.KS
.NH 3
uucp channel
.LP
This has a slightly different RHS syntax which the same as that
produced by
.I pathalias(1 ),
e.g.
.IP
vax1.ee.hw.ac.uk sun2!vax1!%s
.LP
where %s is the user part of the address (converted to uucp form).
.KE
.LP
In the frequent case where the RHS consists of the first token of the LHS
suffixed with "!%s" then the RHS may be omitted. Thus the two
following entries are equivalent:
.DS I
ukc.ac.uk ukc!%s
ukc.ac.uk
.DE
.LP
This again allows a file written completely in this shorthand notation
to be used both as a domain and a channel file.
.NH 3
top channel
.LP
The top channel has a top level domain name on the LHS and a domain name
on the RHS, e.g.
.DS I
uk ukc.ac.uk
.DE
.LP
which states that any address in the
.I "uk"
domain, which did not match a domain name in one of the mailer channel tables,
is sent to
.I ukc.ac.uk .
.LP
If you feel tempted to put
.DS I
%s.com nss.cs.ucl.ac.uk
.DE
.LP
into the tcp channel for example, you should instead put
.DS I
com nss.cs.ucl.ac.uk
.DE
.LP
into the top channel. The latter will use the channel tables to
find a route for
.I "nss.cs.ucl.ac.uk" ,
whereas the latter assumes it is directly connected (via tcp).
If all but a few top domains are relayed by the same
relay, you can use the
.I "DEFAULT"
keyword, e.g.
.DS I
DEFAULT gateway.cs.hw.ac.uk
.DE
.LP
to specify that any top level domains listed in the top domain file,
for which no relay is explictly given, should be sent to the default relay.
On small or infrequently maintained machines, or when there is only
one possible relay, the keyword
.I "ALL"
can be used, e.g.
.DS I
ALL gateway.cs.hw.ac.uk
.DE
.LP
which causes all addresses that are not matched in any other
channel to be sent to the relay even if they do not contain a recognised
top level domain. This allows "slave" style configurations to be built.
.SH
Note
.IP
Make sure that the domains on the RHS of the relaying rules
eventually match some domain on the LHS of a rule in one of the mailer
channel tables.
.LP
.KS
.NH 3
news channel
.LP
This has a newsgroup hierarchy name on the LHS and an optional
relay name on the RHS, for example:
.DS I
comp.binaries.%s sun3
comp.%s
bionet.%s biovax
news.%s
soc.%s
.DE
.KE
.LP
which sends mail for comp.binaries.<anything> to comp.binaries.<..>@sun3
and similarly mails messages to bionet.<anything> to bionet.<..>@biovax
but delivers comp.<anything-else>, news.<anything> and soc.<anything> to
the news system on the local host. The mail-news program from the
Support directory should be installed on all hosts where news is not
relayed elsewhere.
.SH
Note
.IP
The news channel acts on LOCAL USER NAMES not DOMAIN NAMES
.NH 3
bitnet channel
.LP
The bitnet channel has been discontinued. If you need it, you are invited to
re-implement it and send the authors the patches.
.NH 2
Order of channel declarations may be significant
.LP
Channel tables are processed in the order in which they are specified.
When using wildcard rules, it may be necessary to change the order of
channel table declarations, or split a channel table into two files with
another interleaved between them, for the following reason. If two channels
are declared
.DS I
channel tcp file="tcp.chn"
channel ether file="ether.chn"
.DE
.LP
and the files contain
.DS I
# tcp.chn
%s.com

# ether.chn
%s.ncr.com
.DE
.LP
then the tcp channel will 'steal' messages for host.ncr.com, because the
more general wildcard will be processed first. The cure is to reverse the
order of the table declarations in the
.I config.site
file.
.NH 2
Examples
.LP
The directory Examples contains sample channel tables.
These can be used as a starting point for creating your channel tables.
.NH
Site specific modifications to base.m4
.LP
If a file named
.I localise.sh
exists in the configuration directory, it will be executed by
.I Config
to, for example, change details of
.I base.m4
such as the load average above which no work is done. The example
in the Examples directory uses
.I ed(1)
to achieve this.
.NH
Installing the configuration file
.LP
"make test" will invoke sendmail in test mode to enable you to verify
that the configuration can resolve addresses correctly. You should
read the sendmail documentation if you are unfamiliar with this facility.
.LP
There is a shell script called
.I Install.sh
that will install a sendmail
configuration file. Install.sh is called with the following arguments:
.DS C
Install.sh [-f] [-n] [-s] <host> [ <configfile> ]
.DE
.LP
By default, this will copy the <configfile> to /usr/lib/sendmail.cf on <host>,
create a freeze file and then restart the sendmail daemon.
If the
.I -f
option is given a freeze file is
.I not
created. This is usually necessary for shared configurations, or when your
sendmail uses Yellow Pages. The
.I -n
option does not copy the configuration file,
it only restarts the daemon. This is used for all but the first of a group of
hosts which share the same copy of /usr/lib/sendmail.cf via NFS.
The
.I -s
option is used when the
.I target
system has a System V style
.I ps(1) .
.LP
Where a configuration is made for a single host, "make install"
will call Install.sh to install the configuration file for that host.
Where it is shared, a shell script should be set up to call Install.sh for
each of the hosts sharing the configuration.
.SH
Notes
.IP (1)
In versions of Sun software from SunOS 4.0, sendmail.cf lives in /etc so
that /usr/lib can be shared more widely. If you are running the same
sendmail.cf on many clients, put it in /usr/lib and make a symblink from
/etc/sendmail.cf to /usr/lib/sendmail.cf on each client. If you have
an NFS server which serves one configuration to its clients but uses another
itself, put its own in /etc . You will need to write a short script using rcp
and Install.sh -n to handle such a case.
.NH
Checking for name clashes
.LP
"make check" will run
.I Domcheck
on the domain tables and
.I Chncheck
on the channel tables used in the configuration.
These programs will warn you of any name clashes or obvious
syntax errors you have in your tables.
.LP
If you run "make install" from /usr/adm/weekly for example, we recommend
that you instead run "make check install" so that none of the errors which
Domcheck can detect will be put into your live system.